<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Internals</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="ECPG - Embedded SQL in C"
HREF="ecpg.html"><LINK
REL="PREVIOUS"
TITLE="Informix Compatibility Mode"
HREF="ecpg-informix-compat.html"><LINK
REL="NEXT"
TITLE="The Information Schema"
HREF="information-schema.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2011-12-01T22:07:59"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.2 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Informix Compatibility Mode"
HREF="ecpg-informix-compat.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="ecpg.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 33. <SPAN
CLASS="APPLICATION"
>ECPG</SPAN
> - Embedded <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> in C</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="The Information Schema"
HREF="information-schema.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="ECPG-DEVELOP"
>33.16. Internals</A
></H1
><P
>   This section explains how <SPAN
CLASS="APPLICATION"
>ECPG</SPAN
> works
   internally. This information can occasionally be useful to help
   users understand how to use <SPAN
CLASS="APPLICATION"
>ECPG</SPAN
>.
  </P
><P
>    The first four lines written by <TT
CLASS="COMMAND"
>ecpg</TT
> to the
    output are fixed lines.  Two are comments and two are include
    lines necessary to interface to the library.  Then the
    preprocessor reads through the file and writes output.  Normally
    it just echoes everything to the output.
   </P
><P
>    When it sees an <TT
CLASS="COMMAND"
>EXEC SQL</TT
> statement, it
    intervenes and changes it. The command starts with <TT
CLASS="COMMAND"
>EXEC
    SQL</TT
> and ends with <TT
CLASS="COMMAND"
>;</TT
>. Everything in
    between is treated as an <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> statement and
    parsed for variable substitution.
   </P
><P
>    Variable substitution occurs when a symbol starts with a colon
    (<TT
CLASS="LITERAL"
>:</TT
>). The variable with that name is looked up
    among the variables that were previously declared within a
    <TT
CLASS="LITERAL"
>EXEC SQL DECLARE</TT
> section.
   </P
><P
>    The most important function in the library is
    <CODE
CLASS="FUNCTION"
>ECPGdo</CODE
>, which takes care of executing most
    commands. It takes a variable number of arguments. This can easily
    add up to 50 or so arguments, and we hope this will not be a
    problem on any platform.
   </P
><P
>    The arguments are:

    <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>A line number</DT
><DD
><P
>        This is the line number of the original line; used in error
        messages only.
       </P
></DD
><DT
>A string</DT
><DD
><P
>        This is the <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> command that is to be issued.
        It is modified by the input variables, i.e., the variables that
        where not known at compile time but are to be entered in the
        command. Where the variables should go the string contains
        <TT
CLASS="LITERAL"
>?</TT
>.
       </P
></DD
><DT
>Input variables</DT
><DD
><P
>        Every input variable causes ten arguments to be created.  (See below.)
       </P
></DD
><DT
><TT
CLASS="PARAMETER"
>ECPGt_EOIT</TT
></DT
><DD
><P
>        An <TT
CLASS="TYPE"
>enum</TT
> telling that there are no more input
        variables.
       </P
></DD
><DT
>Output variables</DT
><DD
><P
>        Every output variable causes ten arguments to be created.
        (See below.)  These variables are filled by the function.
       </P
></DD
><DT
><TT
CLASS="PARAMETER"
>ECPGt_EORT</TT
></DT
><DD
><P
>        An <TT
CLASS="TYPE"
>enum</TT
> telling that there are no more variables.
       </P
></DD
></DL
></DIV
><P>
   </P
><P
>    For every variable that is part of the <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
>
    command, the function gets ten arguments:

    <P
></P
></P><OL
TYPE="1"
><LI
><P
>       The type as a special symbol.
      </P
></LI
><LI
><P
>       A pointer to the value or a pointer to the pointer.
      </P
></LI
><LI
><P
>       The size of the variable if it is a <TT
CLASS="TYPE"
>char</TT
> or <TT
CLASS="TYPE"
>varchar</TT
>.
      </P
></LI
><LI
><P
>       The number of elements in the array (for array fetches).
      </P
></LI
><LI
><P
>       The offset to the next element in the array (for array fetches).
      </P
></LI
><LI
><P
>       The type of the indicator variable as a special symbol.
      </P
></LI
><LI
><P
>       A pointer to the indicator variable.
      </P
></LI
><LI
><P
>       0
      </P
></LI
><LI
><P
>       The number of elements in the indicator array (for array fetches).
      </P
></LI
><LI
><P
>       The offset to the next element in the indicator array (for
       array fetches).
      </P
></LI
></OL
><P>
   </P
><P
>    Note that not all SQL commands are treated in this way.  For
    instance, an open cursor statement like:
</P><PRE
CLASS="PROGRAMLISTING"
>EXEC SQL OPEN <TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
>;</PRE
><P>
    is not copied to the output. Instead, the cursor's
    <TT
CLASS="COMMAND"
>DECLARE</TT
> command is used at the position of the <TT
CLASS="COMMAND"
>OPEN</TT
> command
    because it indeed opens the cursor.
   </P
><P
>    Here is a complete example describing the output of the
    preprocessor of a file <TT
CLASS="FILENAME"
>foo.pgc</TT
> (details might
    change with each particular version of the preprocessor):
</P><PRE
CLASS="PROGRAMLISTING"
>EXEC SQL BEGIN DECLARE SECTION;
int index;
int result;
EXEC SQL END DECLARE SECTION;
...
EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index;</PRE
><P>
    is translated into:
</P><PRE
CLASS="PROGRAMLISTING"
>/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include &#60;ecpgtype.h&#62;;
#include &#60;ecpglib.h&#62;;

/* exec sql begin declare section */

#line 1 "foo.pgc"

 int index;
 int result;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ?     ",
        ECPGt_int,&#38;(index),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
        ECPGt_int,&#38;(result),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"</PRE
><P>
    (The indentation here is added for readability and not
    something the preprocessor does.)
   </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="ecpg-informix-compat.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="information-schema.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><SPAN
CLASS="PRODUCTNAME"
>Informix</SPAN
> Compatibility Mode</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecpg.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>The Information Schema</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>